Control Widget# PRO

The ControlWidget API enables users to add custom Button or Toggle controls to the iOS Control Center or Lock Screen. Each control is linked to an AppIntent to execute custom script logic. The controls support privacy protection, dynamic state labels, and SFSymbols icons.

#Control Label Type

#ControlWidgetLabel

Represents a label for a control, including the main label or value label in active/inactive state.

#1. ControlWidgetButton

Renders a button control that executes a script intent when tapped.

function ControlWidgetButton(props: ControlWidgetButtonProps): JSX.Element

#ControlWidgetButtonProps

If either activeValueLabel or inactiveValueLabel is provided, both should be specified to ensure proper state display.

#2. ControlWidgetToggle

Renders a toggle control that updates a boolean value using a script intent.

function ControlWidgetToggle<T extends { value: boolean }>(props: ControlWidgetToggleProps<T>): JSX.Element

#ControlWidgetToggleProps<T>

#3. ControlWidget Namespace

namespace ControlWidget

#ControlWidget.parameter: string

A user-defined string parameter set during control configuration. Useful for targeting specific resources (e.g., a device ID or door ID).

#ControlWidget.present(element: VirtualNode): void

Displays the control UI. Only ControlWidgetButton or ControlWidgetToggle elements are supported.

#Usage Notes:

• control_widget_button.tsx must only render a ControlWidgetButton.
• control_widget_toggle.tsx must only render a ControlWidgetToggle.
• To hide the entire control content on the Lock Screen, use privacySensitive on the root.
• To redact only specific labels or values, apply privacySensitive inside ControlWidgetLabel.

#Example:

/// app_intents.tsx
export const ToggleDoorIntent = AppIntentManager.register({
  name: "ToggleDoorIntent",
  protocol: AppIntentProtocol.AppIntent,
  perform: async ({ id, value }: { id: string; value: boolean }) => {
    await setDoorState(id, value)
    ControlWidget.reloadToggles()
  }
})

/// control_widget_toggle.tsx
async function run() {
  const doorId = ControlWidget.parameter || "default"
  const data = await fetchDoorData(doorId)

  ControlWidget.present(
    <ControlWidgetToggle
      privacySensitive
      intent={ToggleDoorIntent({ id: doorId, value: !data.doorOpened })}
      label={{
        title: `Door ${doorId}`,
        systemImage: data.doorOpened ? "door.garage.opened" : "door.garage.closed"
      }}
      activeValueLabel={{ title: "The door is opened" }}
      inactiveValueLabel={{ title: "The door is closed" }}
    />
  )
}

run()

#ControlWidget.reloadButtons(): void

Reloads all control widget buttons. Useful when the intent result changes the UI state.

#ControlWidget.reloadToggles(): void

Reloads all toggle widgets. Call this after a toggle action to update state.

#4. Development Notes

• Every control must be associated with an AppIntent to define its behavior.
• Toggle controls must pass an intent with a parameter shape { value: boolean }.
• If using value labels (activeValueLabel / inactiveValueLabel), always provide both.
• System images (systemImage) should follow SF Symbols naming conventions.
• Use ControlWidget.reloadButtons() and reloadToggles() to force UI updates after state changes in the background.